<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic
  PUBLIC "-//OASIS//DTD DITA Composite//EN" "ditabase.dtd">
<topic id="topic1">
    <title id="bv20941">CREATE SERVER</title>
    <body>
        <p id="sql_command_desc">Defines a new foreign server.</p>
        <section id="section2">
            <title>Synopsis</title>
            <codeblock id="sql_command_synopsis">CREATE SERVER <varname>server_name</varname> [ TYPE '<varname>server_type</varname>' ] [ VERSION '<varname>server_version</varname>' ]
    FOREIGN DATA WRAPPER <varname>fdw_name</varname>
    [ OPTIONS ( [ mpp_execute { 'master' | 'any' | 'all segments' } [, ] ]
                [ num_segments '<varname>num</varname>' [, ] ]
                [ <varname>option</varname> '<varname>value</varname>' [, ... ]] ) ]</codeblock>
        </section>
        <section id="section3">
            <title>Description</title>
            <p><codeph>CREATE SERVER</codeph> defines a new foreign server. The user who defines
               the server becomes its owner.</p>
            <p>A foreign server typically encapsulates connection information that a foreign-data
              wrapper uses to access an external data source. Additional user-specific connection
              information may be specified by means of user mappings.</p>
            <p>Creating a server requires the <codeph>USAGE</codeph> privilege on the foreign-data
              wrapper specified.</p>
        </section>
        <section id="section4">
            <title>Parameters</title>
            <parml>
                <plentry>
                    <pt><varname>server_name</varname></pt>
                    <pd>
                        <p>The name of the foreign server to create. The server name must be unique within the database.</p>
                    </pd>
                </plentry>
                <plentry>
                    <pt><varname>server_type</varname></pt>
                    <pd>
                        <p>Optional server type, potentially useful to foreign-data wrappers.</p>
                    </pd>
                </plentry>
                <plentry>
                    <pt><varname>server_version</varname></pt>
                    <pd>
                        <p>Optional server version, potentially useful to foreign-data wrappers.</p>
                    </pd>
                </plentry>
                <plentry>
                    <pt><varname>fdw_name</varname></pt>
                    <pd>
                        <p>Name of the foreign-data wrapper that manages the server.</p>
                    </pd>
                </plentry>
                <plentry>
                    <pt>OPTIONS ( <varname>option</varname> '<varname>value</varname>' [, ... ] )</pt>
                    <pd>
                        <p>The options for the new foreign server. The options typically define the connection details of the server, but the actual names and values are dependent upon the server's foreign-data wrapper.</p>
                    </pd>
                </plentry>
                <plentry>
                    <pt>mpp_execute { 'master' | 'any' | 'all segments' }</pt>
                    <pd>
                        <p>A Greenplum Database-specific option that identifies the host
                            from which the foreign-data wrapper
                            reads or writes data: <ul id="ul_zcg_2vd_mgb">
                                <li><codeph>master</codeph> (the default)—Read or write data from
                                    the master host.</li>
                                <li><codeph>any</codeph>—Read data from either the master host or
                                    any one segment, depending on which path costs less.</li>
                                <li><codeph>all segments</codeph>—Read or write data from
                                    all segments. To support this option value, the
                                    foreign-data wrapper should have a policy that matches the segments
                                     to data.
                                 <note>Greenplum Database supports parallel writes to foreign tables
                                   only when you set <codeph>mpp_execute 'all segments'</codeph>.</note></li>
                            </ul></p>
                        <p>Support for the foreign server <codeph>mpp_execute</codeph> option,
                            and the specific modes, is foreign-data wrapper-specific.</p> 
                        <p>The <codeph>mpp_execute</codeph> option can be specified in multiple
                            commands: <codeph>CREATE FOREIGN TABLE</codeph>, <codeph>CREATE
                                SERVER</codeph>, and <codeph>CREATE FOREIGN DATA WRAPPER</codeph>.
                            The foreign table setting takes precedence over the foreign server
                            setting, followed by the foreign-data wrapper setting.</p>
                    </pd>
                </plentry>
                <plentry>
                    <pt>num_segments '<varname>num</varname>'</pt>
                    <pd>
                        <p>When <codeph>mpp_execute</codeph> is set to
                          <codeph>'all segments'</codeph>, the Greenplum Database-specific
                          <codeph>num_segments</codeph> option identifies the
                          number of query executors that Greenplum Database spawns on the
                          source Greenplum Database cluster. If you do not provide a value,
                          <varname>num</varname> defaults to the number of segments in the
                          source cluster.</p>
                        <p>Support for the foreign server <codeph>num_segments</codeph> option
                          is foreign-data wrapper-specific.</p>
                    </pd>
                </plentry>
            </parml>
        </section>
        <section id="section5">
            <title>Notes</title>
            <p>When using the dblink module (see <codeph><xref href="../modules/dblink.xml#topic1">dblink</xref></codeph>), you can use the foreign server name as an argument of the <codeph>dblink_connect()</codeph> function to provide the connection parameters. You must have the <codeph>USAGE</codeph> privilege on the foreign server to use it in this manner.</p>
        </section>
        <section id="section6">
            <title>Examples</title>
            <p>Create a foreign server named <codeph>myserver</codeph> that uses the foreign-data wrapper named <codeph>pgsql</codeph> and includes connection options:</p><codeblock>CREATE SERVER myserver FOREIGN DATA WRAPPER pgsql 
    OPTIONS (host 'foo', dbname 'foodb', port '5432');</codeblock>
        </section>
        <section id="section7">
            <title>Compatibility</title>
            <p><codeph>CREATE SERVER</codeph> conforms to ISO/IEC 9075-9 (SQL/MED).</p>
        </section>
        <section id="section8">
            <title>See Also</title>
            <p><codeph><xref href="ALTER_SERVER.xml#topic1">ALTER SERVER</xref></codeph>,
                        <codeph><xref href="DROP_SERVER.xml#topic1">DROP
                    SERVER</xref></codeph>,
                        <codeph><xref href="CREATE_FOREIGN_DATA_WRAPPER.xml#topic1">CREATE
                    FOREIGN DATA WRAPPER</xref></codeph>,
                        <codeph><xref href="CREATE_USER_MAPPING.xml#topic1">CREATE
                    USER MAPPING</xref></codeph></p>
        </section>
    </body>
</topic>
